home *** CD-ROM | disk | FTP | other *** search
/ Aminet 40 / Aminet 40 (2000)(Schatztruhe)[!][Dec 2000].iso / Aminet / dev / misc / IOBlixDevKitR4.lha / IOBlixDevKit / AutoDocs / ioblix.doc next >
Encoding:
Text File  |  2000-09-05  |  19.6 KB  |  527 lines
  1.  
  2. TABLE OF CONTENTS
  3.  
  4. ioblix.resource/--background--
  5. ioblix.resource/AddIRQHook
  6. ioblix.resource/AllocChipList
  7. ioblix.resource/FindChip
  8. ioblix.resource/FreeChipList
  9. ioblix.resource/ObtainChip
  10. ioblix.resource/ObtainChipShared
  11. ioblix.resource/ReleaseChip
  12. ioblix.resource/ReleaseChipShared
  13. ioblix.resource/RemIRQHook
  14. ioblix.resource/SwitchClockPort
  15.  
  16. ioblix.resource/--background--                   ioblix.resource/--background--
  17.  
  18.    PURPOSE
  19.       The ioblix.resource is created by SetupIOBlix during startup and provides
  20.       several functions to gain exclusive as well as shared access to any chip
  21.       the IOBlix multi I/O boards provide. If you ever want to use one of the
  22.       IOBlix chips in a lowlevel manner you should ALWAYS use either
  23.       ObtainChip() or ObtainChipShared() to prevent other ioblix.resource
  24.       conform programs from interferring with your program. All device drivers
  25.       being delivered with your IOBlix board follow this rule. And hopefully all
  26.       third-party drivers will also do. To access these functions just call
  27.       OpenResource(IOBLIXRESNAME) and use the returned pointer in the same
  28.       manner as library bases are used.
  29.  
  30.  
  31. ioblix.resource/AddIRQHook                           ioblix.resource/AddIRQHook
  32.  
  33.    NAME
  34.       AddIRQHook  - add a private interrupt function to the IOBlix interrupt
  35.                     chain
  36.  
  37.    SYNOPSIS
  38.       void = AddIRQHook( node )
  39.                          A0
  40.  
  41.       void AddIRQHook( struct IRQHookNode * );
  42.  
  43.    FUNCTION
  44.       Adds the given node to the IOBlix interrupt chain. This is necessary
  45.       because normal interrupt handling by AmigaOS will loose some interrupts on
  46.       heavy system load.
  47.       Just imagine two applications using the IOBlix board (eg one serial and
  48.       one parallel port). When adding your own interrupt function with Exec's
  49.       AddIntServer() the system will just recognize the first of two
  50.       simultaneously happening interrupts, because the first function will return
  51.       a successfull interrupt handling and Exec will cease any further handling
  52.       within its chain. But at this time the second interrupt has still not been
  53.       processed. IOBlix' own interrupt chain avoids this problem by checking all
  54.       active chips before returning control to Exec.
  55.       The function given in ihn_HookFunc will be passed the data given in
  56.       ihn_HookUserData on the stack. Just as Exec's interrupt handling functions
  57.       a return value of 0 indicates that no interrupt has happened. Any other
  58.       return value indicates a successfull interrupt handling.
  59.  
  60.    INPUTS
  61.       node     -- a correctly initialized IRQHookNode
  62.  
  63.    EXAMPLE
  64.       /* add a private interrupt function */
  65.       ULONG __saveds myIRQFunc( APTR userData);
  66.       APTR myUserData;
  67.       struct IRQHookNode *node;
  68.  
  69.       if (IOBlixBase = OpenResource(IOBLIXRESNAME)) {
  70.         node->ihn_Node.ln_Name = "TestHook";
  71.         node->ihn_Node.ln_Pri = 5; /* priority within the chain */
  72.         node->ihn_HookFunc = myIRQFunc;
  73.         node->ihn_HookUserData = myUserData;
  74.         AddIRQHook(node);
  75.         /* do whatever you want */
  76.         RemIRQHook(node);
  77.       }
  78.  
  79.       ULONG myIRQFunc( APTR userData )
  80.       {
  81.         /* check wether an interrupt has happened or not                   */
  82.         /* if yes, then do all necessary things and return a value of != 0 */
  83.         /* else just return 0                                              */
  84.       }
  85.  
  86.    SEE ALSO
  87.       RemIRQHook
  88.  
  89. ioblix.resource/AllocChipList                     ioblix.resource/AllocChipList
  90.  
  91.    NAME
  92.       AllocChipList -- get a list of all available chips
  93.  
  94.    SYNOPSIS
  95.       list = AllocChipList( void )
  96.       D0
  97.  
  98.       struct List *AllocChipList( void );
  99.  
  100.    FUNCTION
  101.       This function returns a copy of the internal list of all available chips.
  102.       You are allowed to iterate through the list, but you must not change
  103.       anything. All nodes in the list are of type (struct IOBlixChipNode *). No
  104.       chip in the list is obtained in a ObtainChip()-like manner.
  105.  
  106.    RESULTS
  107.       chipNode -- a list of all available chips, or NULL if the call failed
  108.  
  109.    EXAMPLE
  110.       /* print information about all IOBlix chips in the system */
  111.       struct IOBlixResource *IOBlixBase;
  112.       struct List *list;
  113.       struct IOBlixChipNode *node;
  114.  
  115.       if (IOBlixBase = OpenResource(IOBLIXRESNAME)) {
  116.         if (list = AllocChipList()) {
  117.           node = (struct IOBlixChipNode *)chipList->lh_Head;
  118.           while (node->icn_Node.ln_Succ) {
  119.             switch (node->icn_Type) {
  120.               case ICT_Z2_SERIAL_CHIP:
  121.                 printf("IOBlix Z2 UART, %s, %ld bytes FIFO\n",
  122.                        node->icn_Description, node->icns_FIFOSize);
  123.                 break;
  124.               case ICT_Z2_PARALLEL_CHIP:
  125.                 printf("IOBlix Z2 parallel port, %s, %ld bytes FIFO\n",
  126.                        node->icn_Description, node->icnp_FIFOSize);
  127.                 break;
  128.               default:
  129.                 break;
  130.               printf("chip is in use by %s\n",
  131.                      (node->icn_Owner) ? node->icn_Owner : "nobody");
  132.             }
  133.             node = (struct IOBlixChipNode *)node->icn_Node.ln_Succ);
  134.           }
  135.           FreeChipList(list);
  136.         } else {
  137.           printf("failed to allocate chip list\n");
  138.         }
  139.       }
  140.  
  141.    SEE ALSO
  142.       FreeChipList
  143.  
  144. ioblix.resource/FindChip                               ioblix.resource/FindChip
  145.  
  146.    NAME
  147.       FindChip -- find a chip in the resource's database
  148.  
  149.    SYNOPSIS
  150.       chipNode = FindChip(chipType, chipNum)
  151.       D0                  D0        D1
  152.  
  153.       struct IOBlixChipNode *FindChip( ULONG, ULONG );
  154.  
  155.    FUNCTION
  156.       This function searches the internal list for the chip matching the given
  157.       values for chip type and number. If the search is successfull the chip's
  158.       information block is returned, but the chip is NOT obtained!
  159.       You may use this function just to check if a certian chip is available
  160.       and to get some information about it. All fields in IOBlixChipNode are
  161.       considered READ-ONLY, you must not change anything.
  162.  
  163.    INPUTS
  164.       chipType -- the type of chip you want to find
  165.       chipNum  -- internal number of the chip you want to find
  166.                   valid range is 0..IOBLIX_Z2_NUM_SERUNITS for UARTs
  167.                                  0..IOBLIX_Z2_NUM_PARUNITS for parallel ports
  168.                                  0..IOBLIX_Z2_NUM_FIFOUNITS for external FIFOs
  169.                   to obtain a chip on multiple IOBlix boards use
  170.                   boardNum*10+chipNum as value, ie 13 is the third UART on the
  171.                   second board
  172.  
  173.    RESULTS
  174.       chipNode -- a pointer to the chip's information block, or NULL if the
  175.                   chip is not available.
  176.  
  177.    EXAMPLE
  178.       /* try to find serial unit 0 on first IOBlix board */
  179.       struct IOBlixResource *IOBlixBase;
  180.       struct IOBlixChipNode *chipInfo;
  181.  
  182.       if (IOBlixBase = OpenResource(IOBLIXRESNAME)) {
  183.         if (chipInfo = FindChip(ICT_Z2_SERIAL_CHIP, 0)) {
  184.           /* chip is available, let's see what it is able to do */
  185.           printf("UART is a %s with %ld bytes FIFO"\n,
  186.                  chipInfo->icn_Description, chipInfo->icns_FIFOSize);
  187.           printf("UART is in use by %s\n",
  188.                  (chipInfo->icn_Owner) ? chipInfo->icn_Owner : "nobody");
  189.         } else {
  190.           printf("serial port #0 is not available\n");
  191.         }
  192.       }
  193.  
  194.    SEE ALSO
  195.       ReleaseChip, FindChip
  196.  
  197. ioblix.resource/FreeChipList                       ioblix.resource/FreeChipList
  198.  
  199.    NAME
  200.       FreeChipList -- free a previously allocated chip list
  201.  
  202.    SYNOPSIS
  203.       void = FreeChipList( list )
  204.                            A0
  205.  
  206.       void FreeChipList( struct List * );
  207.  
  208.    FUNCTION
  209.       This function frees the given list again.
  210.  
  211.    INPUTS
  212.       list     -- a list previously allocated by AllocChipList(). Passing NULL
  213.                   is a no-op.
  214.  
  215.    SEE ALSO
  216.       AllocChipList
  217.  
  218. ioblix.resource/ObtainChip                           ioblix.resource/ObtainChip
  219.  
  220.    NAME
  221.       ObtainChip -- obtain a chip for exclusive use
  222.  
  223.    SYNOPSIS
  224.       chipNode = ObtainChip(chipType, chipNum, newOwner, oldOwner)
  225.       D0                    D0        D1          A0        A1
  226.  
  227.       struct IOBlixChipNode *ObtainChip( ULONG, ULONG, UBYTE *, UBYTE ** );
  228.  
  229.    FUNCTION
  230.       This function attempts to obtain the specified chip for exclusive use.
  231.       The name newOwner is used as an identifier to tell other programs who
  232.       currently has obtained the chip.
  233.       If the chip is not in use by anybody then the IOBlixChipNode of this chip
  234.       is returned to show a successfull allocation. If the chip is already in
  235.       use then the return value will be NULL, and the identifier of the using
  236.       program is retured in oldOwner, if a valid pointer is given. If also
  237.       oldOwner is still NULL then the chip is not available.
  238.  
  239.    INPUTS
  240.       chipType -- the type of chip you want to obtain
  241.       chipNum  -- internal number of the chip you want to obtain
  242.                   valid range is 0..IOBLIX_Z2_NUM_SERUNITS for UARTs
  243.                                  0..IOBLIX_Z2_NUM_PARUNITS for parallel ports
  244.                                  0..IOBLIX_Z2_NUM_FIFOUNITS for external FIFOs
  245.                   to obtain a chip on multiple IOBlix boards use
  246.                   boardNum*10+chipNum as value, ie 13 is the third UART on the
  247.                   second board
  248.       newOwner -- a string to identify you as the current owner of the chip
  249.       oldOwner -- pointer to a string where the identfier of a previous owner
  250.                   will be placed. If NULL then it will not be used.
  251.  
  252.    RESULTS
  253.       chipNode -- If the chip is available and not in use then chipNode will be
  254.                   a pointer to IOBlixChipNode, which contains various
  255.                   information about the chip. If the chip is either not
  256.                   available or already obtained by someone else, this function
  257.                   will return NULL. Use oldOwner to check if the chip is
  258.                   already in use.
  259.       oldOwner -- If given a valid pointer and the chip is obtained by someone
  260.                   else, the previous allocators identifier will be placed here.
  261.  
  262.    EXAMPLE
  263.       /* try to obtain serial unit 0 on first IOBlix board */
  264.       struct IOBlixResource *IOBlixBase;
  265.       struct IOBlixChipNode *chipInfo;
  266.       UBYTE *oldOwner = NULL;
  267.  
  268.       if (IOBlixBase = OpenResource(IOBLIXRESNAME)) {
  269.         if (chipInfo = ObtainChip(ICT_Z2_SERIAL_CHIP, 0, "Test", &oldOwner)) {
  270.           /* chip is obtained now, do whatever you want */
  271.           ReleaseChip(chipInfo);
  272.         } else {
  273.           if (oldOwner) {
  274.             printf("serial port #0 is in use by %s\n", oldOwner);
  275.           } else {
  276.             printf("serial port #0 is not available\n");
  277.           }
  278.         }
  279.       }
  280.  
  281.    SEE ALSO
  282.       ObtainChipShared, ReleaseChip, ReleaseChipShared, FindChip
  283.  
  284. ioblix.resource/ObtainChipShared               ioblix.resource/ObtainChipShared
  285.  
  286.    NAME
  287.       ObtainChipShared -- obtain a chip for shared use
  288.  
  289.    SYNOPSIS
  290.       chipNode = ObtainChipShared(chipType, chipNum, newOwner, oldOwner)
  291.             D0                    D0        D1          A0        A1
  292.  
  293.       struct IOBlixChipNode *ObtainChipShared( ULONG, ULONG,
  294.                                                UBYTE *, UBYTE ** );
  295.  
  296.    FUNCTION
  297.       This function attempts to obtain the specified chip for shared use.
  298.       The name newOwner is used as an identifier to tell other programs who
  299.       currently has obtained the chip.
  300.       If the chip is not in use by anybody or already obtained in shared mode
  301.       then the IOBlixChipNode of this chip is returned to show a successfull
  302.       allocation. If the chip is already obtained in exclusive mode the return
  303.       value will be NULL, and the identifier of the using program is retured in
  304.       oldOwner, if a valid pointer is given. If also oldOwner is still NULL then
  305.       the chip is not available.
  306.  
  307.       When using a chip in shared mode you MUST use the semaphore contained in
  308.       the returned IOBlixChipNode while accessing the chip with Exec's semaphore
  309.       functions to gain exclusive access for a short time. After that you MUST
  310.       give access back to the system again with exec.library/ReleaseSemaphore.
  311.       When you got access to the chip you should save the important registers of
  312.       the chip (ie the control register of a parallel port), then put the values
  313.       you need there. Before calling ReleaseSemaphore() on the IOBlixChipNode's
  314.       semaphore you should put the previously saved values back to the important
  315.       registers to leave the chip in a specified state.
  316.  
  317.       When this call succeeds the ICFF_SHARED flag will be set in the chip
  318.       node's icn_Flags field. It will remain set unless the last user has
  319.       released the chip with ReleaseChipShared(). The list
  320.       icn_SharedAccessorList contains all users, while icn_Owner just contains
  321.       the string "shared use".
  322.  
  323.    INPUTS
  324.       chipType -- the type of chip you want to obtain
  325.       chipNum  -- internal number of the chip you want to obtain
  326.                   valid range is 0..IOBLIX_Z2_NUM_SERUNITS for UARTs
  327.                                  0..IOBLIX_Z2_NUM_PARUNITS for parallel ports
  328.                                  0..IOBLIX_Z2_NUM_FIFOUNITS for external FIFOs
  329.                   to obtain a chip on multiple IOBlix boards use
  330.                   boardNum*10+chipNum as value, ie 13 is the third UART on the
  331.                   second board
  332.       newOwner -- a string to identify you as the current owner of the chip
  333.       oldOwner -- pointer to a string where the identfier of a previous owner
  334.                   will be placed. If NULL then it will not be used.
  335.  
  336.    RESULTS
  337.       chipNode -- If the chip is available and not in use then chipNode will be
  338.                   a pointer to IOBlixChipNode, which contains various
  339.                   information about the chip. If the chip is either not
  340.                   available or already obtained by someone else, this function
  341.                   will return NULL. Use oldOwner to check if the chip is
  342.                   already in use.
  343.       oldOwner -- If given a valid pointer and the chip is obtained by someone
  344.                   else, the previous allocators identifier will be placed here.
  345.  
  346.    EXAMPLE
  347.       /* try to obtain serial unit 0 on first IOBlix board */
  348.       struct IOBlixResource *IOBlixBase;
  349.       struct IOBlixChipNode *chipInfo;
  350.       struct UARTRegisters *uart;
  351.       UBYTE *oldOwner = NULL;
  352.       UBYTE scratch
  353.  
  354.       if (IOBlixBase = OpenResource(IOBLIXRESNAME)) {
  355.         if (chipInfo = ObtainChipShared(ICT_Z2_SERIAL_CHIP, 0,
  356.                                         "Test", &oldOwner)) {
  357.           /* chip is obtained in shared mode now */
  358.           uart = (struct UARTRegisters *)chipInfo->icn_ChipRegisters;
  359.  
  360.           /* now access the chip exclusively for a short time */
  361.           ObtainSemaphore(&chipInfo->icn_SharedAccessSema);
  362.  
  363.           /* first save some importan registers */
  364.           scratch = *uart->ur_scr;
  365.  
  366.           /* now do whatever you want */
  367.           *uart->ur_scr = 0x42;
  368.  
  369.           /* put back the saved registers */
  370.           *uart->ur_scr = scratch;
  371.  
  372.           /* release the chip from exclusive access */
  373.           ReleaseSemaphore(&chipInfo->icn_SharedAccessSema);
  374.  
  375.           /* completely release the chip */
  376.           ReleaseChipShared(chipInfo, "Test");
  377.         } else {
  378.           if (oldOwner) {
  379.             printf("serial port #0 is in use by %s\n", oldOwner);
  380.           } else {
  381.             printf("serial port #0 is not available\n");
  382.           }
  383.         }
  384.       }
  385.  
  386.    SEE ALSO
  387.       ObtainChip, ReleaseChip, ReleaseChipShared, FindChip
  388.  
  389. ioblix.resource/ReleaseChip                         ioblix.resource/ReleaseChip
  390.  
  391.    NAME
  392.       ReleaseChip -- release a previously obtained chip from exclusive use
  393.  
  394.    SYNOPSIS
  395.       ReleaseChip(chipNode)
  396.                   A0
  397.  
  398.       void ReleaseChip( struct IOBlixChipNode * );
  399.  
  400.    FUNCTION
  401.       ReleaseChip() is the inverse of ObtainChip(). After calling ReleaseChip()
  402.       the given chip is available again for others.
  403.  
  404.       Each ObtainChip() call must be balanced by exactly one ReleaseChip() call.
  405.       Needless to say, havoc breaks out if the task releases a chip more times
  406.       than it has obtained it.
  407.  
  408.    INPUTS
  409.       chipNode -- the node previously returned by ObtainChip(). Passing NULL is
  410.                   a no-op.
  411.  
  412.    NOTES
  413.       Never release a shared obtained chip with ReleaseChip()!
  414.  
  415.    SEE ALSO
  416.       ObtainChip, ObtainChipShared, ReleaseChipShared
  417.  
  418. ioblix.resource/ReleaseChipShared             ioblix.resource/ReleaseChipShared
  419.  
  420.    NAME
  421.       ReleaseChipShared -- release a previously obtained chip from shared use
  422.  
  423.    SYNOPSIS
  424.       ReleaseChipShared(chipNode, owner)
  425.                         A0        A1
  426.  
  427.       void ReleaseChipShared( struct IOBlixChipNode *, UBYTE * );
  428.  
  429.    FUNCTION
  430.       ReleaseChipShared () is the inverse of ObtainChipShared().
  431.  
  432.       Each ObtainChipShared() call must be balanced by exactly one
  433.       ReleaseChipShared() call. Needless to say, havoc breaks out if the task
  434.       releases a chip more times than it has obtained it. The chip remains in
  435.       shared mode unless all obtainers have released it.
  436.  
  437.       You should call ReleaseChipShared() with the same owner name as
  438.       ObtainChipShared(), else the chip will remain obtained.
  439.  
  440.       When the last obtainer calls ReleaseChipShared() the ICFF_SHARED flag will
  441.       be reset.
  442.  
  443.    INPUTS
  444.       chipNode -- the node previously returned by ObtainChipShared(). Passing
  445.                   NULL is a no-op.
  446.       owner    -- the same owner as used for ObtainChipShared()
  447.  
  448.  
  449.    NOTES
  450.       Never release an exclusively obtained chip with ReleaseChipShared()!
  451.  
  452.    SEE ALSO
  453.       ObtainChip, ObtainChipShared, ReleaseChip
  454.  
  455. ioblix.resource/RemIRQHook                           ioblix.resource/RemIRQHook
  456.  
  457.    NAME
  458.       RemIRQHook  - remove a previously installed interrupt function
  459.  
  460.    SYNOPSIS
  461.        RemIRQHook( node )
  462.                     A0
  463.  
  464.       void RemIRQHook( struct IRQHookNode * );
  465.  
  466.    FUNCTION
  467.       Removes the given node from IOBlix' own interrupt chain.
  468.  
  469.    INPUTS
  470.       node     -- a correctly initialized IRQHookNode
  471.  
  472.    SEE ALSO
  473.       AddIRQHook
  474.  
  475. ioblix.resource/SwitchClockPort                 ioblix.resource/SwitchClockPort
  476.  
  477.    NAME
  478.       SwitchClockPort - switch the Quaddddroport to another slot
  479.  
  480.    SYNOPSIS
  481.       SwitchClockPort( port )
  482.                         D0
  483.  
  484.       void SwitchClockPort( LONG port );
  485.  
  486.    FUNCTION
  487.       Switches the QuaddddroPort to the given slot. All further accesses to a
  488.       module connected to an A1200's clockport will be redirected to the
  489.       selected slot. Slot 0 is the default slot. After finishing the access you
  490.       should switch back to port 0, to give other hardware the chance to work in
  491.       its intended way, because it doesn't know the QuaddddroPort exists.
  492.       SwitchClockPort() is only necessary if you need to access another port
  493.       than port 0.
  494.  
  495.    NOTES
  496.       A SwitchClockPort() call should be surrounded by a pair of
  497.       Disable()/Enable() to avoid interferrence with other programs. Therefore
  498.       every access after SwitchClockPort() must obey the rules that apply for
  499.       Disable() and must be done VERY quick.
  500.       Doing a simple Forbid()/Permit() pair isn't enough, because any interrupt
  501.       handler could interfere with your program.
  502.       This function of course assumes you have ObtainChip()'ed or
  503.       ObtainChipShared()'ed the desired chip before you access it. Else strange
  504.       and unpredictable things can and will happen!
  505.  
  506.    INPUTS
  507.       port     -- the slot to be switched to, valid values are 0 to 4
  508.  
  509.    EXAMPLE
  510.  
  511.       LONG expPort = chipInfo->icn_ExpanderPort;
  512.  
  513.       if (expPort > 0) {
  514.         Disable();
  515.         SwitchClockPort(expPort);
  516.       }
  517.       /* do your hardware access here and do it QUICK! */
  518.       if (expPort > 0) {
  519.         SwitchClockPort(0);
  520.         Enable();
  521.       }
  522.  
  523.    SEE ALSO
  524.       exec.library/Disable, exec.library/Enable
  525.  
  526.  
  527.